6.0 Summary of Requirements Addressed

Provide a cross-platform XML interface to the CallManager database.

7.0 Resolved Severity 6 Defects

8.0 Message/Interface Compliance Summary/Support Matrix

Compliance with XML Schema 1.0.  XML Schema compliance was tested with a 3rd party application called XML Spy version 4.x.  Early versions of MSXML schema validator did not support enough of the XML Schema 1.0 recommendation to be used.

AXL complies with SOAP 1.0 as defined by the World Wide Web Consortium.

Compliance with HTTP 1.1.

9.0 Caveats

10.0 Platform Considerations

There are no platform considerations. The client is only required to be able to send an HTTP request to the AXL endpoint.

11.0 Lower Layer Transport Protocol Implications

The AXL API runs under IIS and can only be accessed via HTTP.

12.0 Message/Interface Definition

12.1 Legend

The AXL schema is attached as an HTML document (see section 12.2), which graphically describes each request and response.  The following legend explains the graphics used in the schema document.

 

Request or Response	Element Name	Description
	Complex Element	A complex element can have child elements, as well as attributes. An element with a solid border is required to appear in an XML instance document.
	Simple Element	A simple element cannot have child elements but can have attributes. An element with a solid border is required to appear in an XML instance document.
	Optional Element	An optional element is not required to appear in an instance of the XML. Any type of element can be optional, including sequence and choice elements.
	Sequence Element	A sequence means that all children of this element must appear in the XML in the order that they are listed.
	Choice Element	A choice element means that only one of the children of this element can appear in the XML.

12.2 Individual Message Defiitions

Individual messages are defined here.

13.0 Message Sequence Charts

14.0 Performance and Scalability

Throttling of Requests

The side-effects of updating the Cisco CallManager database can adversely affect system performance; therefore, the system administrator is capable of controlling how many AXL requests are allowed to update the database per minute.  This value is controlled via the Database Layer service parameter “MaxAXLWritesPerMinute”.

AXL accommodates all requests until the “MaxAXLWritesPerMinute” value is reached. Subsequent attempts to modify the database with AXL will be rejected with an HTTP 503 Service Unavailable response.  Every minute, AXL will reset its internal counter and begin to accept AXL update requests until the limit is reached again.

The following AXL request are considered "Reads" and do not count against the "MaxAXLWritesPerMinute" service parameter. All other AXL requests not in this list count against the service parameter:

• executeSQLQuery
• doDeviceReset
• all AXL "get" requests
• all AXL "list" requests

15.0 Packaging

N/A.

16.0 Licensing Considerations

N/A.

17.0 Operations, Administration, and Maintenance (OA&M)

18.0 Security

18.1 Authentication

Anonymous access to the AXL SOAP service should be deactivated to enforce user authentication.  User authentication is controlled via the HTTP Basic Authentication scheme. Therefore, you must include the Authorization header in the HTTP Header.

For example, if the user agent wishes to send the userid "larry" and password "curly and moe", it would use the following header field:

Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==

Where the string "bGFycnk6Y3VybHkgYW5kIG1vZQ==" is the Base 64 encoding of "larry:curly and moe".

18.2 Data Encryption

If the user agent wishes to encrypt the AXL SOAP message, then the user agent must use HTTP SSL.

SSL is not functional on the web server by default.  The customer must request and install a SSL Certificate from a certified authority such as VeriSign.  Once the SSL Certificate has been installed on the web server, AXL requests can be made using the “https” protocol in lieu of “http”.

19.0 Integration considerations and Inter-operability

The AXL API gives enormous power to developers to modify the CallManager system database. The developer must take caution when using AXL, since each API call impacts the system. Abuse of the API can lead to dropped calls and slower system performance.  AXL is not intended as a real-time API, but as a provisioning and configuration API.

If AXL is determined to be using too much of the CPU time, consider lowering the MaxAXLWritesPerMinute service parameter (see section 14).  If this does not solve the problem, consider purchasing a second server to be used only by applications using AXL.

20.0 Patentability

21.0 Troubleshooting

21.1 Error Codes

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"  

SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

    <SOAP-ENV:Body>

        <SOAP-ENV:Fault>

            <faultcode>SOAP-ENV:Client</faultcode>

            <faultstring>

            <![CDATA[

            An error occurred during parsing

            Message: End element was missing the character '>'.

            Source = Line : 41, Char : 6

            Code : c00ce55f, Source Text : </re

            ]]>

            </faultstring>

        </SOAP-ENV:Fault>

    </SOAP-ENV:Body>

<SOAP-ENV:Envelope  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" S

OAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

    <SOAP-ENV:Body>

        <SOAP-ENV:Fault>

            <faultcode>SOAP-ENV:Client</faultcode>

            <faultstring>Device not found with name SEP003094C39708.</faultstring>

            <detail  xmlns:axl="http://www.cisco.com/AXL/1.0" 

                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  

                     xsi:schemaLocation="http://www.cisco.com/AXL/1.0 

                                         http://myhost/CCMApi/AXL/V1/axlsoap.xsd">

                <axl:error  sequence="1234">

                    <code>0</code>

                    <message>

<![CDATA[

Device not found with name SEP003094C39708.

]]>

                   </message>

                   <request>doDeviceLogin</request>

               </axl:error>

           </detail>

        </SOAP-ENV:Fault>

    </SOAP-ENV:Body>

·         request

The <request> element is provided so that the user agent can determine what type of request generated this error.  This element is optional; therefore it may not always appear.

22.0 Open Issues/Risks/Dependencies

23.0 Reference Documents

24.0 Sample Code (Optional)

The following examples describe how to make an AXL request and read back the response to the request.  Each SOAP request must be sent to the web server via an HTTP POST.  The endpoint URL is an ISAPI Extension DLL.  The following list contains the only four required HTTP headers.

·         POST /CCMApi/AXL/V1/soapisapi.dll

The first header identifies that this particular POST is intended for the AXL SOAP API.  The AXL API only responds to the POST method.

·         content-type: text/xml

The second header confirms that the data being sent to AXL is XML.  If this header is not found then an HTTP 415 error is returned to the client.

·         Authorization: Basic <some Base 64 encoded string>

The third header is the Base64 encoding of the user name and password for the administrator of the AXL Server.  If authentication of the user fails, then an HTTP 401 Access Denied error is returned to the client.

·         content-length: <a positive integer>

The fourth header is the length (in bytes) of the AXL request.

Note:  Currently, the content-length cannot exceed 40 kilobytes.  If a request is received, which is greater than 40 kilobytes, then an HTTP 413 error message is returned.

The following example contains an HTTP header for an AXL SOAP request:

POST /CCMApi/AXL/V1/soapisapi.dll

Host: axl.myhost.com:80

Accept: text/*

Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==

Content-type: text/xml

Content-length: 613

The following AXL request will be used in the code examples displayed in the following sections.  This is an example of a getPhone request:

POST /CCMApi/AXL/V1/soapisapi.dll Host: axl.myhost.com:80 Accept: text/* Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ== Content-type: text/xml Content-length: 613   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">     <SOAP-ENV:Body>         <axl:getPhone xmlns:axl="http://www.cisco.com/AXL/1.0" xsi:schemaLocation="http://www.cisco.com/AXL/1.0 http://ccmserver/schema/axlsoap.xsd"  sequence="1234">             <phoneName>SEP222222222245</phoneName>         </axl:getPhone>     </SOAP-ENV:Body> </SOAP-ENV:Envelope>

24.1          C/C++ Example

This code example uses a hard-coded AXL request and sends it to the AXL Server running on the local system (localhost).  It then reads the response back, outputting the response to the screen.

#include <winsock2.h>           // required for sockets #include <iostream>             // required for console I/O #include <sstream> #include <string>               // required for std::string   using namespace std;     int main(int argc, char* argv[]) { // make connection to server   WSADATA WSAData;   // initialize sockets if (int iError = WSAStartup (MAKEWORD(2,0), &WSAData)) {        cout << "Windows Sockets startup error. Aborting." << endl;        return -1; }   SOCKET Socket = socket (AF_INET, SOCK_STREAM, IPPROTO_TCP);   if (Socket == INVALID_SOCKET) {        cout << "Socket creation error. Aborting." << endl;        return -1; }   SOCKADDR_IN sinRemote;   sinRemote.sin_family = AF_INET; sinRemote.sin_port = htons (80) ; sinRemote.sin_addr.s_addr =  inet_addr( "127.0.0.1" );   cout << "connecting to service" << endl; int retval = connect(Socket, (SOCKADDR *)&sinRemote, sizeof (sinRemote));               if (retval != 0) {        cout << "Error occured while connecting to socket. Aborting." << endl;        closesocket(Socket);        return -1; } const int BUFSIZE = 2048; char buff[BUFSIZE];           // the temporary receive buffer string strHTTPHeader;         // the HTTP Header string strAXLRequest;         // the AXL SOAP request   // The AXL request:  getPhone strAXLRequest = “<SOAP-ENV:Envelope xmlns:SOAP- \ ENV=\”http://schemas.xmlsoap.org/soap/envelope/\” \ xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" \ xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"> \ <SOAP-ENV:Body> \ <axl:getPhone xmlns:axl=\"http://www.cisco.com/AXL/1.0\" \ xsi:schemaLocation=\"http://www.cisco.com/AXL/1.0 \ http://ccmserver/schema/axlsoap.xsd\" sequence=\"1234\"> \ <phoneName>SEP222222222245</phoneName> \ </axl:getPhone> \ </SOAP-ENV:Body> \ </SOAP-ENV:Envelope>”;   // temporarily use the buffer to store the length of the request sprintf(buff, “%d”, strAXLRequest.length());   // build the HTTP header   strHTTPHeader = "POST /CCMApi/AXL/V1/soapisapi.dll\r\n \ Host: localhost:80\r\n \ Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==\r\n \ Accept: text/*\r\n \ Content-type: text/xml\r\n \ Content-length: ";   strHTTPHeader += buff; strHTTPHeader += “\r\n\r\n”; // put the HTTP header and SOAP XML together strAXLRequest = strHTTPHeader + strAXLRequest;   // send these bytes to the socket retval = send (Socket, strAXLRequest.c_str(),strAXLRequest.length(), 0);   if ( retval != SOCKET_ERROR) {        // output response        cout << "received response: " << endl;          int iTotalRead = 0;        // read BUFSIZE at a time, writing to another ostringstream          do {               iNumRead = recv (Socket, buff, BUFSIZE-1, 0);               buff[iNumRead] = NULL;                 cout << buff;               iTotalRead += iNumRead;                      } while (iNumRead == BUFSIZE-1);          cout << "Read " << iTotalRead << " bytes." << endl;        } else {        cout << "An error occured while sending the data to socket." << endl; }   // all finished, close socket  closesocket(Socket); return 0;     }

24.2          Java Example

This code example uses a hard-coded AXL request and sends it to the AXL Server running on the local system (localhost).  It then reads the response back, outputting the response to the screen.

import java.io.*; import java.net.*;   public class main { public static void main(String[] args) {        //Declare references        String sAXLSOAPRequest = null;        // will hold the complete request,                                               // HTTP header and SOAP payload          String sAXLRequest = null;            // will hold only the SOAP payload               Socket socket = null;                 // socket to AXL server        OutputStream out = null;              // output stream to server        InputStream in = null;                // input stream from server        byte[] bArray = null;                 // buffer for reading response from server               // Build the HTTP Header        sAXLSOAPRequest = "POST /CCMApi/AXL/V1/soapisapi.dll\r\n";        sAXLSOAPRequest += "Host: localhost:80\r\n";        sAXLSOAPRequest += "Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==\r\n";        sAXLSOAPRequest += "Accept: text/*\r\n";        sAXLSOAPRequest += "Content-type: text/xml\r\n";        sAXLSOAPRequest += "Content-length: ";               // Build the SOAP payload        sAXLRequest = "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\" ";        sAXLRequest += "xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"> ";        sAXLRequest += "<SOAP-ENV:Body> <axl:getPhone xmlns:axl=\"http://www.cisco.com/AXL/1.0\" ";        sAXLRequest += " xsi:schemaLocation=\"http://www.cisco.com/AXL/1.0 http://ccmserver/schema/axlsoap.xsd\" ";        sAXLRequest += "sequence=\"1234\"> <phoneName>SEP222222222245</phoneName> ";        sAXLRequest += "</axl:getPhone> </SOAP-ENV:Body> </SOAP-ENV:Envelope>";               // finish the HTTP Header        sAXLSOAPRequest += sAXLRequest.length();        sAXLSOAPRequest += "\r\n\r\n";               // now add the SOAP payload to the HTTP header, which completes the AXL SOAP request        sAXLSOAPRequest += sAXLRequest;               // now that the message has been built, we can connect to server and send it        try        {               socket = new Socket("localhost", 80);                             out = socket.getOutputStream();               in = socket.getInputStream();                             // send the request to the host               out.write(sAXLSOAPRequest.getBytes());                 // read the response from the host               StringBuffer sb = new StringBuffer(2048);               bArray = new byte[2048];               int ch = 0;               int sum = 0;               while ( (ch = in.read(bArray)) != -1 )               {                      sum += ch;                      sb.append(new String(bArray, 0, ch));                                }                             socket.close();               // output the response to the standard out               System.out.println(sb.toString());                      } catch (UnknownHostException e)        {               System.err.println("Error connecting to host: " + e.getMessage());               return;        } catch (IOException ioe)        {               System.err.println("Error sending/receiving from server: " + ioe.getMessage());                             // close the socket               try               {                      if (socket != null) socket.close();               } catch (Exception exc)               {                      System.err.println("Error closing connection to server: " + exc.getMessage());               }               return;        }

25.0 Attachments

25.1 Document Review Action Item